home *** CD-ROM | disk | FTP | other *** search
/ Cream of the Crop 1 / Cream of the Crop 1.iso / PROGRAM / OPTANS10.ARJ / OPTANSI.DOC < prev    next >
Text File  |  1992-06-14  |  60KB  |  1,295 lines
  1. *******************************************************************************
  2.  
  3.                                OptANSI Library
  4.                                  version 1.0
  5.                          Copyright 1992 Michael Dannov
  6.  
  7.                   Optimizing ANSI Output Library for Borland C
  8.  
  9. *******************************************************************************
  10.                                 DOCUMENTATION
  11. ------------------------------------------------------------------------------
  12. *ABOUT OPTANSI*
  13.  
  14. What is the OptANSI Library?
  15.      OptANSI was designed to output fully optimized and compressed ANSI codes
  16. on the fly to any ANSI interpreting device. It is NOT an interpreter by any
  17. means, so it does not receive incoming ANSI and convert it into logical screen
  18. output. Usually this control is left to the ANSI device or the comm program.
  19.  
  20. Who can use the OptANSI Library?
  21.      Anyone who programs in Borland C and has need to use the ANSI screen
  22. interface can use OptANSI. It is well suited for most communication appli-
  23. cations like BBS programs, remote doorways, fossil drivers, telecommunication
  24. programs, and BBS doors. It can also be used with ANSI drawing packages and
  25. other ANSI utilities. In fact, it has been used to design the popular AOPT
  26. (ANSI Optimizer) utility which takes standard .ANS files and reduces them to
  27. their minimum size without affecting resulting output. You may also find other
  28. uses for OptANSI if you simply want an alternative method for screen output
  29. aside from VIDEO BIOS, direct screen, or DOS calls. All OptANSI functions can
  30. be piped through DOS if you use standard printf() and other DOS forwarding
  31. calls, thereby allowing you to send screen locations and color codes to the
  32. screen or to a file. This is especially useful if standard conio is not always
  33. appropriate or compatible; for instance, DOS shells using telecommunications
  34. without a gateway.
  35.  
  36. Why use the OptANSI Library, say as opposed to another?
  37.      There are a number of generic ANSI libraries out there to use. I might
  38. have used them myself if I hadn't grown so critical of all the wasted time
  39. sending unnecessary codes. ANSI is a slow interface by design and there is
  40. little sense wasting good process time on unneeded output. For instance, say
  41. you are using your 2400 baud modem online with a BBS who's sysop loves
  42. switching between those ANSI colors. It takes a lot of time to draw the screen
  43. at that speed and any sort of optimization at all could be beneficial. OptANSI
  44. will practically never result in slower output even if your application uses
  45. 14400 baud transfers. OptANSI should not impede output times; it can only
  46. benefit them.
  47.      OptANSI functions will produce output that is 10-30% smaller of all
  48. output sent (ie, ANSI and all other text) compared with other libraries. Of
  49. pure ANSI output, OptANSI produces 20-60% smaller output. Both these figures
  50. are dependant on how intensive your the of ANSI.
  51.      Another important feature is that OptANSI has ten times the number of
  52. functions as other libraries. It's true, many of these are macros that call
  53. coded functions, but the underlying code and data (if ALL functions in the
  54. library are used) occupies less than 1.5K of memory.
  55.  
  56. How can I use OptANSI Library?
  57.      First, link the OptANSI LIBrary file to your project. Second, all OptANSI
  58. functions are very similar to conio functions, so it shouldn't be to much of
  59. a strain to learn and use. The function names use a one letter suffix "a" for
  60. ANSI. An example is gotoxy(x, y) which in OptANSI is agotoxy(x, y, &x, &y).
  61. OptANSI functions are very tight. Much of the code is written in assembly
  62. using optimized BC asm inlines. Also, the library is spread out so that only
  63. functions called by your program are actually linked into the executable.
  64.  
  65. How does OptANSI work?
  66.      OptANSI, unlike rival libraries, remembers critical information about its
  67. former states, like last cursor position and previous color. OptANSI takes
  68. advantage of all the ASCII and ANSI rules to take advantage of all possible
  69. shortcuts and will 99.9% of the time find the shortest output path.
  70.  
  71. There seem to be a number of ANSI standards; by which one does OptANSI comply?
  72.      OptANSI is mostly composed of a combination of the shared rules of many
  73. different ANSI devices or at least their expected operations. There have been
  74. bugs in various ANSI drivers released over the last 10 years. ANSI.SYS which
  75. accompanies DOS is no exception. OptANSI has been tested with most public ANSI
  76. drivers and certain flags have been implemented to allow the programmer or the
  77. user (if designed to do so) to decide which outputs are valid to optimize.
  78.      OptANSI also includes a number of functions that the programmer can
  79. decide whether or not to implement. Some of the NANSI (New ANSI) and other
  80. ANSI extensions have been included like insert line, delete line, insert
  81. spaces, delete spaces, etc.
  82.  
  83. Performance Results from ALL output sent:
  84.                            Raw      OptANSI       Other libraries   FNs
  85. WWIV BBS Capture (*):      69180    56241 - 19%   70683 + 2%        1
  86. PCBoard Capture (*):       41335    39374 - 5%    47763 + 15%       1
  87. Wildcat (*):               26639    19665 - 26%   27213 + 2%        1,2
  88. Doorway, Rmt DOS Capture:  51308    42610 - 17%   55389 + 8%        2,1
  89. TheDraw ANSI:              24271    23521 - 3%    28253 + 16%       2,1
  90.  
  91. Raw - Raw Output
  92. OptANSI - Raw Output retransmit through OptANSI
  93. Other Libraries - Raw Output retransmit through other libraries
  94. FNs - Primary ANSI functions were (in order of probability):
  95.         1 - Color Functions
  96.         2 - Location Functions
  97.         3 - Miscellaneous Functions
  98.  
  99. (*)  Results from BBS Systems are based on ANSI captures during a regular
  100. session with ANSI on. This includes newscanning files (FN 1), reading a
  101. message (FN1), writing a single reply with a full screen editor if available
  102. (FN 1,2), etc.
  103.  
  104. PCBoard's ANSI is pretty well optimized.
  105.  
  106. NOTE: The values above are probably not reflective of performance for your
  107. applications since many of the above programs have already been optimized,
  108. which goes to prove that it is probably a good idea.
  109.  
  110.  
  111. ------------------------------------------------------------------------------
  112. *REGISTERING OPTANSI*
  113.  
  114.      As a registered owner of the OptANSI library, you will get complete
  115. source code to the library. You can modify the source code to fit your needs
  116. if necessary, but you can never give out the OptANSI based source code even if
  117. it is modified beyond recognition. You also may not use the OptANSI library to
  118. make a competing library. Ergo, you cannot use OptANSI to make an optimizing
  119. ansi library that you distribute or sell to others, not even for other
  120. platforms [unless you get written permission from the author]. Also, there
  121. exists a copyright notice in the data of ainit. This does not need to be
  122. displayed anywhere in your programs, but must remain in the final executable.
  123. Do not remove this code from ainit.c. Other restrictions apply based on which
  124. license you pay. See below.
  125.  
  126.      No Royalties Apply to OptANSI library licenses. However, different
  127. licenses have different prices. Please read the information about each license
  128. option below to ensure that one you select is the one that satisfies your
  129. qualifications. Limitations apply to each. If you have questions or require
  130. special considerations, please contact the author listed below.
  131.  
  132.     -LICENSE OPTION------------------------------------ -REG PRICE-
  133.      Private license                                        $15
  134.      Shareware license                                      $30
  135.      Small commercial license                               $50
  136.      Full commercial license                                $500
  137.  
  138.      Printed documentation                              ADD $10
  139.      All Future Upgrades                                    $5
  140.  
  141. Private License: OptANSI library can only be included in software written
  142. which is NOT FOR SALE. Ie, it is part of your cost for doing business. One
  143. license applies to one person or one business depending on the licensee's
  144. name. Subcontractors or other developers must license one OptANSI library for
  145. each individual or company that he programs for that requires OptANSI. Markup
  146. in such cases may apply but is only appropriate up to 33%.
  147.  
  148. Shareware license: OptANSI library can only be included in software written
  149. which are for sales in the shareware market only. One license applies to all
  150. shareware products written by the same licensed author or business.
  151. [Shareware courtesy.]
  152.  
  153. Small commercial license: OptANSI library can be included in software written
  154. which is for sale commercially, but is limited to only those applications
  155. whose primary sales comes from direct sale to a customer and not through a
  156. retailer. One license is necessary for each separate software package (of a
  157. different name) that you sell which uses OptANSI functions.
  158.  
  159. Full commercial license: OptANSI library can be included in software written
  160. for any commercial sales. This includes products which are resold or sold at
  161. software stores. One license is necessary for each software package (of a
  162. different name) that you sell which uses OptANSI functions.  
  163.  
  164.      The prices above are very small representations of actual development
  165. costs in each scenario; especially considering the hundreds of hours you would
  166. need to develop the equivalent of OptANSI. Special considerations will be
  167. considered if prices are unrealistic for your purpose. If you need more
  168. licensing freedom, contact the author at an address listed below.
  169.  
  170. *ADDRESS*                                *HOME BBS* -> email Michael Dannov
  171. Michael Dannov                           Programmer Tech Industries
  172. 18102 Brookhurst ST, Ste M Box #176      714-220-1561
  173. Fountain Valley, CA 92708                PCBoard/Qmail, 14400 HST, 24hrs
  174.                                            (General/Programming)
  175.  
  176. ------------------------------------------------------------------------------
  177. *INFORMATION ABOUT ANSI*
  178.  
  179.      ANSI is a useful extension to standard output which normally behaves like
  180. teletype. Teletype output cannot change screen colors or access all the
  181. different locations on the screen. It can only write text data, moving down
  182. and to the right on the screen. ANSI extensions break this barrier and add
  183. these functions. It works by sending a special sequence of characters (below)
  184. which tell the interpreter what to do.
  185.  
  186.                       ESC [ Num ; .. Cmd
  187.  
  188.       ESC is the character 27
  189.       Num is a number value in text format like "15"
  190.       Cmd is a command character which identifies how to behave
  191.       ; separates multiple number parameters
  192.  
  193.      To use ANSI from DOS, you must use some form of ANSI emulator. One
  194. accompanies DOS called ANSI.SYS. If you place DEVICE=ANSI.SYS in your
  195. CONFIG.SYS, ANSI will be installed. Other authors have put other versions of
  196. ANSI into the mainstream. They include FANSI, NANSI, DEVSYS, etc. PC Magazine
  197. has also released a memory resident version of ANSI (with some PCBoard
  198. extensions) which can be placed in your AUTOEXEC.BAT instead of CONFIG.SYS.
  199. Also, some manufacturers of video cards have offered replacement ANSI.SYS
  200. files on their resource disks. In my experience, these versions of ANSI have
  201. been the most incompatible with ANSI rules. If asked to recommend a best ANSI
  202. for all needs, I would probably have to suggest a version of NANSI because it
  203. adds many useful extensions and is 3 times faster than DOS' ANSI.
  204.  
  205.      To use ANSI from a telecommunications program or other program, make sure
  206. to turn ANSI emulation on. NOTE to programmers writing applications for
  207. telecommunications: QMODEM has one inconsistency with ansi colors. Make sure
  208. to explain to QModem users that they should turn on Strict Colors in the
  209. Video|Toggles menu of the options screen, or else they risk reset colors not
  210. being right.
  211.  
  212.  
  213. *OPTANSI BASICS*
  214.  
  215.      To use OptANSI, include OPTANSI.H at the top of your program. This header
  216. includes many shortcut macros and defines all the OptANSI function prototypes.
  217.  
  218.      OptANSI's functions return a pointer to an ANSI string (char *) back to
  219. the main function instead of using hardcoded output resources. This allows
  220. programmers to use their own string output functions. This is especially
  221. critical if you're going to be using telecommunications or other output
  222. routines without a fossil driver.
  223.  
  224.      Most OptANSI functions share a 15 char buffer area used in the creation
  225. of ANSI output strings. This is more than enough for an optimized ANSI string.
  226. However, you must note that this does place a constraint on OptANSI use. Every
  227. OptANSI function needs to be called on a separate line. Ie, you cannot pass
  228. multiple OptANSI functions through the same output function.
  229.  
  230. This is invalid:
  231.  
  232.      printf("%s%sHi", acolor(31), agotoxy(25, 10, &x, &y));
  233.  
  234. This is better:
  235.  
  236.      printf(acolor(31));
  237.      printf(agotoxy(25, 10, &x, &y));
  238.      printf("Hi");
  239.  
  240.      Make sure to send OptANSI functions on separate lines. Even though the
  241. last 2 lines could have been combined as printf("%sHi", agotoxy(...)); it is
  242. better to get into the practice of keeping them on separate lines.
  243.  
  244.      Another solution exists that allows you to use OptANSI function names
  245. instead of each time passing them through an output function like printf(). To
  246. use this option, include AUSER.H after OPTANSI.H. This file is filled with
  247. useful macros which expand OptANSI function names into full expressions using
  248. an output function of your choice. For instance, instead of:
  249.  
  250.      printf(agotoxy(1, 1, &x, &y));
  251.  
  252. you could put:
  253.  
  254.      agotoxy(1, 1, &x, &y); 
  255.  
  256. because AUSER.H defines:
  257.  
  258.      #define aout(s) printf(s)   // This macro you can define to your reqs
  259.      #define agotoxy(x, y, ox, oy)  aout(agotoxy(x, y, ox, oy))
  260.  
  261.      This is a useful shortcut and the recommended means of operation because
  262. it treats each OptANSI function like already familiar conio functions, and
  263. because it automatically ensures that each function is called on its own
  264. separate line, resolving the above dilemma.
  265.  
  266. NOTE ABOUT USING printf and other text output functions:
  267.      There is one problem with using functions like printf or other output
  268. functions. There is a problem because these output routines do not keep store
  269. a variable that keeps track of the current x and y cursor coordinates and
  270. OptANSI location functions need to know this information in order to optimize
  271. new points. It is therefore recommended that if you are writing your own
  272. output routines that you make your functions know their current screen
  273. positions. If you use the likes of printf or other text output functions, you
  274. might need to update x & y by using wherex() and wherey() before using
  275. location functions. It is your responsibility that these variables stay
  276. accurate. See location functions for more information.
  277.  
  278.  
  279.      Because some ANSI emulators behave differently than others in some
  280. respects, a set of flags have been assigned to allow you to determine how some
  281. optimizations behave. This char variable is called ashortcuts. It's purpose
  282. is to determine if some sequence of characters does not behave like expected.
  283. These optimization are labeled in OPTANSI.H as:
  284.  
  285.      1  aBKSP     Set if backspace (char 8, ^H) is nondestructive.
  286.      2  aLF       Set if linefeed (char 10, ^J) moves cursor down only, if
  287.                     false, assumes LF is equivalent to CR/LF combination.
  288.      4  aCR       Set if carriage return (char 13, ^M) moves the cursor to
  289.                     left margin of the same line only.
  290.      8  aCLRSCR   Set if clear screen (char 12, ^L) clears the entire screen
  291.                     to the current color. Telix requires this on.
  292.     64  aRESET    Set if reset color (ESC[m) resets the color to lightgray on
  293.                     black (7), almost always true. See ashorttelecom() notes.
  294.    128  aNANSI    Set if you want to use NANSI or FANSI extensions. See
  295.                     Compilation Notes for more information on this flag.
  296.  
  297.      Two macros are defined in OPTANSI.H to help assign ashortcuts a proper
  298. value. Example usage is below:
  299.  
  300.      ashort(aBKSP | aCR | aRESET);  // This will turn on BKSP, CR, and RESET
  301.                                     // and set ashortcuts=69
  302. or you could say:
  303.  
  304.      anotshort(aLF | aCLRSCR | aNANSI); // Will set all flags on except aLF, 
  305.                                         // aCLRSCR, and aNANSI
  306.  
  307.      Depending on the output device you send these controls to, these general
  308. rules apply and these macros can be used:
  309.  
  310. ashortdos()
  311.      for printf() & other dos output functions: (ashortcuts defaults to this mode)
  312.        aBKSP | aCR | !aLF | !aCLRSCR | aRESET
  313.  
  314. ashorttelecom()
  315.      telecommunications:
  316.        !aBKSP | aCR | aLF | aCLRSCR | aRESET
  317.        - In some telecom progs, backspace can be set to nondestructive, it is
  318.          best to assume this is not true and use !aBKSP and be sure
  319.        - In QModem, if Strict Colors is on, use aRESET, else !aRESET
  320.        - CR/LF modes are usually turned off
  321.        - Telix should have aCLRSCR true, otherwise it will not clear the
  322.          screen to the current color.
  323.  
  324.      There are three parts to the OptANSI function library. The first is
  325. miscellaneous color functions. The second is color functions. And the last is
  326. location functions.
  327.  
  328. *MISCELLANEOUS FUNCTIONS*
  329.  
  330.  
  331. #########
  332. # ainit # Initialize OptANSI functions, variables
  333. #########
  334. Declaration:  int ainit()                         function
  335.  
  336. Remark: ainit is not necessary to be called to use OptANSI functions. Its only
  337. purpose is to define OptANSI global variables. It may be good practice to
  338. include it at the top of your program in case of future versions require it.
  339.  
  340.  
  341. ########
  342. # acmd # Return an ANSI string based on parameters
  343. ########
  344. Declaration:  char *acmd(char num, char cmd)      function
  345.  
  346. Remark: Returns an ANSI string in the form: ESC [ num cmd. Num is expanded
  347. into a string. This function operates as a universal for common ANSI
  348. expressions. If num is 0 or 1, num will not expanded. To force 1 to be
  349. expanded, use instead the macro SP_ONE, like acmd(SP_ONE, 'K').
  350. NOTE: Be careful - If you use this command to change colors or move on the
  351. screen manually, you MUST update the global variables corresponding to the
  352. command.
  353.  
  354. Example:
  355.      acmd(2, 'J');       // Sends ESC[2J which clears the screen
  356.      axpos=1;            // Must update axpos & aypos
  357.      aypos=1;
  358.  
  359.  
  360. #########
  361. # atest # Send ANSI test presence string, Request cursor location
  362. #########
  363. Declaration:  char *atest()                       function
  364.  
  365. Remark: Returns the ANSI request string. If ANSI is present, the ANSI emulator
  366. will send back a standardized string. If atest is sent to standard output
  367. (printf or equivalent), it will put this response string in the keyboard
  368. buffer. See awherexy() and aresult() for logical next step.
  369.  
  370.  
  371. ##########
  372. # atest1 # Flush Standard input buffer then Send ANSI test presence string,
  373. ##########   Request cursor location.
  374. Declaration:  char *atest1()                      function
  375.  
  376. Remark: Same as atest above except that it is specialized for standard io.
  377. This way the keyboard buffer will be cleared to eliminate any possibility of
  378. error. See awherexy() and aresult1() for logical next step.
  379.  
  380.  
  381. ###########
  382. # aresult # Test atest response string
  383. ###########
  384. Declaration:  int aresult(char *str)              function
  385.  
  386. Remark: Compare str to expected result string. If true, it returns 1,
  387. otherwise 0 for false. The aresult() function should follow atest().
  388.  
  389. Example:
  390.      char s[15];
  391.      atest();
  392.      readbuf(&s);    // reads input buffer until enter
  393.      if (aresult(s)) {
  394.        ...
  395.      } else 
  396.        printf("ANSI Not Available");
  397.  
  398.  
  399. ############
  400. # aresult1 # Read keyboard buffer and tests atest response string
  401. ############
  402. Declaration:  int aresult1()                      function
  403.  
  404. Remark: This function is similar to aresult except that it is specialized for
  405. standard io. It does not need an outside function to read in the atest result
  406. string. It will read the keyboard buffer for you. It then compares this string
  407. to that expected response. If true, it returns 1, otherwise 0 for false. The
  408. aresult1() function should follow atest1().
  409.  
  410. Example:
  411.      atest1();
  412.      if (aresult1()) {
  413.        ...
  414.      } else 
  415.        printf("ANSI Not Available");
  416.  
  417.  
  418. ############
  419. # aresult2 # Test interrupts for presence of ANSI
  420. ############
  421. Declaration:  int aresult2()                      function
  422.  
  423. Remark: This function is similar to aresult except that it tests the computer
  424. interrupts directly. It does not require atest to determine if ANSI is
  425. present. If ANSI is present, it returns 1, otherwise 0 for false.
  426.  
  427. NOTE: This function is only available for DOS 4.0+ ANSI.SYS. Most 3rd party
  428. ANSI drivers include this installation test.
  429.  
  430. Example:
  431.      if (aresult2()) {
  432.        ...
  433.      } else 
  434.        printf("ANSI Not Available");
  435.  
  436.  
  437. #############
  438. # aupdatexy # Update axpos and aypos to current locations on screen
  439. #############
  440. Declaration:  aupdatexy()                         macro-> calls wherex, wherey
  441.  
  442. Remark: This function is useful in keeping axpos and aypos equal to the
  443. current cursor coordinates. It is necessary to call before OptANSI location
  444. functions if you don't have an output routine that calculates axpos and aypos
  445. as it outputs. However, This function is only useful locally and not for
  446. telecommunications. For telecommunications, the output function should
  447. calculate x and y positions automatically.
  448.  
  449. Example:
  450.      printf("This is a test\n");  // axpos & aypos isn't updated
  451.      aupdatexy();                 // This updates axpos and aypos
  452.      agotoxy(5, 1);               // Now, this will work
  453.  
  454.  
  455. ##############
  456. # aupdatexy1 # Update axpos and aypos to current locations on screen
  457. ##############
  458. Declaration:  aupdatexy1()                        macro-> points to low mem
  459.  
  460. Remark: This function is the same as aupdatexy() above except that instead of
  461. calling the interrupts, it points to low memory where x and y cursor positions
  462. for page 0 are stored (x-0:450, y-0:451). Use this only if you are positive
  463. that these low memory positions are reliable measures of x and y.
  464.  
  465.  
  466. ###########
  467. # aclrscr # Clears the screen and homes the cursor
  468. ###########
  469. Declaration:  char *aclrscr()                     function
  470.  
  471. Remark: Returns an optimized ANSI string that will clear the screen and home
  472. the cursor, axpos=1 and aypos=1, usually clears the screen to the current
  473. color. See location functions. Equivalent to conio's clrscr() function. Telix
  474. requires ashortcuts aCLRSCR to be true because ANSI's ESC sequence will clear
  475. the screen to the default terminal color.
  476.  
  477.  
  478. ###########
  479. # aclreol # Clears the line from the cursor to the end of the line
  480. ###########
  481. Declaration:  char *aclreol()                     function
  482.  
  483. Remark: Returns an ANSI string that will clear the line from the current
  484. cursor position to the end of the line, usually clears to the current color.
  485. Equivalent to conio's clreol() function. Telix clears to the default terminal
  486. color.
  487.  
  488.  
  489. ----------------
  490.  
  491.      The functions below are within ANSI specifications but for some reason
  492. very rarely implemented. It is therefore recommended that they not be used
  493. unless you can ensure that they will work on your intended platform.
  494.  
  495.      Some of the result possibilities are listed below in the windows. Six
  496. emulators have been tested. Assume the most recent versions of each. You may
  497. have to test others if they are not listed. Note carefully that some emulators
  498. will clear or move the cursor and others will not.
  499.  
  500.  
  501. ###########
  502. # aclrbol # Clear line from cursor to beginning of line
  503. ###########
  504. Declaration:  char *aclrbol()                     macro-> calls acmd
  505.  
  506. Remark: Returns an ANSI string that will clear the line from the current
  507. cursor position to the beginning of the line. This function is rarely
  508. supported by ANSI emulators. Different behaviors are listed below:
  509.    ┌──────────────┬──────┬─────────────────────────────────────────────┐
  510.    │Misc Function │Interp│Behavior                                     │
  511.    ├──────────────┼──────┼─────────────────────────────────────────────┤
  512.    │              │ANSI  │None                                         │
  513.    │ ClrBol       │NANSI │Same as clreol                               │
  514.    │              │FANSI │Clears left of cursor to beginning of line   │
  515.    │   ESC[1K     │QMODEM│Same as clreol                               │
  516.    │              │PCPLUS│Clears cursor and left to beginning of line  │
  517.    │              │TELIX │Clears cursor and left to beginning of line  │
  518.    └──────────────┴──────┴─────────────────────────────────────────────┘
  519.  
  520.  
  521. ############
  522. # aclrline # Clears entire line
  523. ############
  524. Declaration:  char *aclrline()                    macro-> calls acmd
  525.  
  526. Remark: Returns an ANSI string that will clear the entire line, but not delete 
  527. the line, cursor does not move. This function is rarely supported by ANSI
  528. emulators. Different behaviors are listed below:
  529.    ┌──────────────┬──────┬─────────────────────────────────────────────┐
  530.    │Misc Function │Interp│Behavior                                     │
  531.    ├──────────────┼──────┼─────────────────────────────────────────────┤
  532.    │              │ANSI  │None                                         │
  533.    │ ClrLine      │NANSI │Same as clreol                               │
  534.    │              │FANSI │Clears entire line, moves cursor to x=1      │
  535.    │   ESC[2K     │QMODEM│Same as clreol                               │
  536.    │              │PCPLUS│Clears entire line, moves cursor to x=1, BUG │ **
  537.    │              │TELIX │Clears entire line                           │
  538.    └──────────────┴──────┴─────────────────────────────────────────────┘
  539.    - Procomm Plus has a bug with this function. The cursor stays at the same
  540.      position, but its internal value for the x position is set to 1, so as
  541.      soon as a character is sent, it is displayed at the old cursor position,
  542.      and then moves the cursor to position 2 on the same line.
  543.  
  544.  
  545. ################
  546. # aclrscrabove # Clears screen above and left of cursor position
  547. ################
  548. Declaration:  char *aclrscrabove()                macro-> calls acmd
  549.  
  550. Remark: Returns an ANSI string that will clear the entire screen above and
  551. left of the cursor, cursor does not move. This function is rarely supported by
  552. ANSI emulators. Different behaviors are listed below:
  553.    ┌──────────────┬──────┬─────────────────────────────────────────────┐
  554.    │Misc Function │Interp│Behavior                                     │
  555.    ├──────────────┼──────┼─────────────────────────────────────────────┤
  556.    │              │ANSI  │Same as clrscr                               │
  557.    │ ClrScrAbove  │NANSI │Clears everything above and left of cursor   │
  558.    │              │FANSI │Clears everything above and left of cursor   │
  559.    │   ESC[1J     │QMODEM│Clears cursor and everything above and left  │
  560.    │              │PCPLUS│Clears cursor and everything above and left  │
  561.    │              │TELIX │Clears cursor and everything above and left  │
  562.    └──────────────┴──────┴─────────────────────────────────────────────┘
  563.  
  564.  
  565. ################
  566. # aclrscrbelow # Clears screen below and right of cursor position
  567. ################
  568. Declaration:  char *aclrscrbelow()                macro-> calls acmd
  569.  
  570. Remark: Returns an ANSI string that will clear the entire screen below and
  571. right of the cursor, cursor does not move. This function is rarely supported
  572. by ANSI emulators. Different behaviors are listed below:
  573.    ┌──────────────┬──────┬─────────────────────────────────────────────┐
  574.    │Misc Function │Interp│Behavior                                     │
  575.    ├──────────────┼──────┼─────────────────────────────────────────────┤
  576.    │              │ANSI  │Same as clrscr                               │
  577.    │ ClrScrBelow  │NANSI │Clears cursor and everything below and right │
  578.    │              │FANSI │Clears cursor and everything below and right │
  579.    │   ESC[J      │QMODEM│Clears cursor and everything below and right │
  580.    │              │PCPLUS│Clears cursor and everything below and right │
  581.    │              │TELIX │Clears cursor and everything below and right │
  582.    └──────────────┴──────┴─────────────────────────────────────────────┘
  583.  
  584.  
  585. ############
  586. # ainsline # Insert a line before the current line
  587. ############
  588. Declaration:  char *ainsline(char y)              macro-> calls acmd
  589.  
  590. Remark: Returns an ANSI string that inserts y lines before the current line.
  591. Different behaviors are listed below:
  592.    ┌──────────────┬──────┬─────────────────────────────────────────────┐
  593.    │Misc Function │Interp│Behavior                                     │
  594.    ├──────────────┼──────┼─────────────────────────────────────────────┤
  595.    │              │ANSI  │Displays L                                   │
  596.    │ InsertLine   │NANSI │Inserts # lines starting at the current line │
  597.    │              │FANSI │Rotates entire current line down # lines     │
  598.    │   ESC[#L     │QMODEM│None                                         │
  599.    │              │PCPLUS│Inserts # lines starting at the current line │
  600.    │              │TELIX │Inserts # lines starting at the current line │
  601.    └──────────────┴──────┴─────────────────────────────────────────────┘
  602.  
  603.  
  604. ############
  605. # adelline # Delete lines starting at current
  606. ############
  607. Declaration:  char *adelline(char y)              macro-> calls acmd
  608.  
  609. Remark: Returns an ANSI string that deletes y lines starting at the current
  610. line. Different behaviors are listed below:
  611.    ┌──────────────┬──────┬─────────────────────────────────────────────┐
  612.    │Misc Function │Interp│Behavior                                     │
  613.    ├──────────────┼──────┼─────────────────────────────────────────────┤
  614.    │              │ANSI  │Displays M                                   │
  615.    │ DeleteLine   │NANSI │Deletes # lines starting at the current line │
  616.    │              │FANSI │Deletes # lines starting at the current line │
  617.    │   ESC[#M     │QMODEM│Freeze Input until ESC pressed               │
  618.    │              │PCPLUS│Freeze Input until ESC pressed               │
  619.    │              │TELIX │Deletes # lines starting at the current line │
  620.    └──────────────┴──────┴─────────────────────────────────────────────┘
  621.  
  622.  
  623. ############
  624. # ainschar # Insert chars starting at cursor
  625. ############
  626. Declaration:  char *ainschar(char x)              macro-> calls acmd
  627.  
  628. Remark: Returns an ANSI string that inserts x spaces starting from the cursor
  629. position. Characters that go past the right margin are deleted. Different
  630. behaviors are listed below:
  631.    ┌──────────────┬──────┬─────────────────────────────────────────────┐
  632.    │Misc Function │Interp│Behavior                                     │
  633.    ├──────────────┼──────┼─────────────────────────────────────────────┤
  634.    │              │ANSI  │Displays @                                   │
  635.    │ InsertChars  │NANSI │Inserts # spaces starting at cursor          │
  636.    │              │FANSI │Inserts # spaces starting at cursor          │
  637.    │   ESC[#@     │QMODEM│Displays ESC sequence                        │
  638.    │              │PCPLUS│Inserts # spaces starting at cursor          │
  639.    │              │TELIX │Inserts # spaces starting at cursor          │
  640.    └──────────────┴──────┴─────────────────────────────────────────────┘
  641.  
  642.  
  643. ############
  644. # adelchar # Deletes characters starting at cursor
  645. ############
  646. Declaration:  char *adelchar(char x)              macro-> calls acmd
  647.  
  648. Remark: Returns an ANSI string that deletes x characters starting at the
  649. cursor. Different behaviors are listed below:
  650.    ┌──────────────┬──────┬─────────────────────────────────────────────┐
  651.    │Misc Function │Interp│Behavior                                     │
  652.    ├──────────────┼──────┼─────────────────────────────────────────────┤
  653.    │              │ANSI  │Displays P                                   │
  654.    │ DeleteChar   │NANSI │Deletes # characters starting at cursor      │
  655.    │              │FANSI │Deletes # characters starting at cursor      │
  656.    │   ESC[#P     │QMODEM│Displays ESC sequence                        │
  657.    │              │PCPLUS│Deletes # characters starting at cursor      │
  658.    │              │TELIX │Deletes # characters starting at cursor      │
  659.    └──────────────┴──────┴─────────────────────────────────────────────┘
  660.  
  661.  
  662.  
  663. *COLOR FUNCTIONS*
  664.  
  665.      The color functions define acurattr a char. This variable is updated to
  666. reflect the current color after each OptANSI color function. If you change the
  667. current color by other means, you will need to update acurcolor on your own.
  668. If you do not, optimizations will make improper assumptions and actual
  669. resulting colors might not match desired.
  670.  
  671.      All functions will only return an ANSI string when necessary. Changing
  672. the current color to the same color value that acurattr already holds will
  673. send back a null string.
  674.  
  675. These color values are defined by OPTANSI.H or CONIO.H:
  676.      0    BLACK          dark colors
  677.      1    BLUE
  678.      2    GREEN
  679.      3    CYAN
  680.      4    RED
  681.      5    MAGENTA
  682.      6    BROWN
  683.      7    LIGHTGRAY
  684.      8    DARKGRAY       light colors
  685.      9    LIGHTBLUE
  686.      10   LIGHTGREEN
  687.      11   LIGHTCYAN
  688.      12   LIGHTRED
  689.      13   LIGHTMAGENTA
  690.      14   YELLOW
  691.      15   WHITE
  692.  
  693.       8   HIGHLIGHT      add to first 0-7 only
  694.     128   BLINK          add to full color attributes only
  695.      
  696.  
  697. ########
  698. # ATTR # Calculate color from foreground and background values
  699. ########
  700. Declaration:  char ATTR(char fr, char bk)         macro (math)
  701.  
  702. Remark: This macro returns a character value, calculated from foreground and
  703. background values (0-15 each) and expands it into a full 8 bit color
  704. attribute. 
  705.  
  706. If you want to use the BLINK macro with ATTR, use it after ATTR:
  707.      ATTR(fr, bk)+BLINK
  708.  
  709. Example:
  710.      i=ATTR(WHITE /*15*/, BLUE /*1*/);     -> returns value 31
  711.  
  712.  
  713. #####################
  714. # acolor, atextattr # *Change current color/attribute 
  715. #####################
  716. Declaration:  char *acolor(char nc)               function
  717.               char *atextattr(char nc)            macro-> calls acolor
  718.  
  719. Remark: Returns an optimized ANSI string that will change the active color,
  720. acurattr is also set to nc. Equivalent to conio's textattr(). Full foreground,
  721. background, highlight, and blink bits can be modified. Acceptable values for
  722. nc are 0-255. See ATTR() for quick method of calculating colors.
  723.  
  724. * This is the recommended method of changing colors.
  725.  
  726.  
  727. ###############
  728. # aforcecolor # Forces color to new color value ignoring optimizations
  729. ###############
  730. Declaration:  char *aforcecolor(char nc)          macro-> calls acolor
  731.  
  732. Remark: Returns a full ANSI string that will change the current active color,
  733. accurattr is also set to nc. This function is like acolor except that it will
  734. send the complete ANSI string as if the color was reinitialized, ie it ignores
  735. last acurattr value when returning changing the color. For instance, lets say
  736. that you are worried about line noise through the modem and acurattr possibly
  737. becomes obscured, aforcecolor(7) would ensure that color 7 is set by ignoring
  738. internal optimizations.
  739.  
  740.  
  741. ##############
  742. # atextcolor # Change current foreground color
  743. ##############
  744. Declaration:  char *atextcolor(char nf)           macro-> calls acolor
  745.  
  746. Remark: Returns an optimized ANSI string that will change the active fore-
  747. ground color, only the first four bits of acurattr are updated. Equivalent to
  748. conio's textcolor(). Foreground and highlight bits can be modified. Acceptable
  749. values for nf are 0-15. Larger values can result in unexpected colors.
  750.  
  751.  
  752. ###################
  753. # atextbackground # Change current background color
  754. ###################
  755. Declaration:  char *atextbackground(char nb)      macro-> calls acolor
  756.  
  757. Remark: Returns an optimized ANSI string that will change the active back-
  758. ground color, only the last four bits of acurattr are updated. Equivalent to
  759. conio's textbackground(). Background and blink bits can be modified.
  760. Acceptable values for nb are 0-15. Larger values can result in unexpected
  761. colors.
  762.  
  763.  
  764. ##########################
  765. # ahighlight, ahighvideo # Set highlight bit of current color
  766. ##########################
  767. Declaration:  char *ahighlight()                  function
  768.               char *ahighvideo()                  macro-> calls ahighlight
  769.  
  770. Remark: Returns an optimized ANSI string that will turn highlight on, only the
  771. highlight bit 4 of acurattr is updated. Equivalent to conio's highvideo().
  772.  
  773.  
  774. ############################
  775. # anohighlight, alowvideo, # Clear highlight bit of current color
  776. # anormvideo, adim         #
  777. ############################
  778. Declaration:  char *anohighlight()                macro-> calls acolor
  779.               char *alowvideo()                   macro-> calls anohighlight
  780.               char *anormvideo()                  macro-> calls anohighlight
  781.               char *adim()                        macro-> calls acolor
  782.  
  783. Remark: Returns an optimized ANSI string that will turn highlight off, only
  784. the highlight bit (4) of acurattr is updated. Equivalent to conio's lowvideo()
  785. and normvideo().
  786.  
  787.  
  788. ##########
  789. # ablink # Set blink bit of current color
  790. ##########
  791. Declaration:  char *ablink()                      function
  792.  
  793. Remark: Returns an optimized ANSI string that will turn blink on, only the
  794. blink bit (8) of acurattr is updated.
  795.  
  796.  
  797. ############
  798. # anoblink # Clear blink bit of current color
  799. ############
  800. Declaration:  char *anoblink()                    macro-> calls acolor
  801.  
  802. Remark: Returns an optimized ANSI string that will turn blink off, only the
  803. blink bit (8) of acurattr is updated.
  804.  
  805.  
  806. ###############
  807. # aresetcolor # Sets color to reset color, White on Black (7)
  808. ###############
  809. Declaration:  char *aresetcolor()                 macro-> calls acolor
  810.  
  811. Remark: Returns an optimized ANSI string that will reset the current color to
  812. lightgray on black*, acurattr is set to 7.
  813.  
  814. Discrepancy of QModem:
  815.    ┌──────────────┬──────┬──────────┬───┬──────────┬───┐
  816.    │Color Function│Interp│Foreground│HiL│Background│Blk│
  817.    ├──────────────┼──────┼──────────┼───┼──────────┼───┤
  818.    │*Reset        │OTHERS│ ltgray 7 │off│ black  0 │off│
  819.    │   ESC[0m     │QMODEM│(default) │(d)│(default) │off│ ashortcuts |= !aRESET
  820.    │or ESC[m      │QMODEM│ ltgray 7 │off│ black  0 │off│ ashortcuts |= aRESET
  821.    └──────────────┴──────┴──────────┴───┴──────────┴───┘
  822.    - QModem uses the default screen text variable found in the options menu to
  823.      define the Reset color. If Strict Color (Video|Toggle) is set to ON, then
  824.      Reset color behaves normally.
  825.  
  826.  
  827. ----------------
  828.  
  829.      The color functions below are not well standardized by ANSI emulators,
  830. therefore their use is not recommended unless necessary. They are not included
  831. in acolor optimizations. YOU MUST update acurattr to reflect the new color
  832. manually.
  833.  
  834.      Some of the color result possibilities are listed below in the windows.
  835. Six emulators have been tested. Assume the most recent versions of each. You
  836. may have to test others if they are not listed. Only boxes with values change.
  837. Those left empty do not.
  838.  
  839.  
  840. ##############
  841. # aunderline # Set current color to a color defined by underline command
  842. ##############
  843. Declaration:  char *aunderline(equation)          macro-> calls acmd
  844.  
  845. Remark: Returns an ANSI string that will change to underline color, acurattr
  846. must be updated manually. Equation is designed for this purpose. Use equation
  847. in the form: acurattr=xxx where xxx is the value you expect acurattr will
  848. result. If you leave equation blank, make sure to update acurattr on a
  849. separate line. You MUST update acurattr or you could get unexpected colors.
  850.    ┌──────────────┬──────┬──────────┬───┬──────────┬───┐
  851.    │Color Function│Interp│Foreground│HiL│Background│Blk│
  852.    ├──────────────┼──────┼──────────┼───┼──────────┼───┤
  853.    │              │ANSI  │ blue   1 │   │          │   │
  854.    │ Underline    │NANSI │ blue   1 │   │          │   │
  855.    │              │FANSI │          │   │          │   │ none
  856.    │   ESC[4m     │QMODEM│ ltgray 7 │off│          │off│
  857.    │              │PCPLUS│ blue   1 │   │ black  0 │   │ **
  858.    │              │TELIX │          │   │          │   │ none
  859.    └──────────────┴──────┴──────────┴───┴──────────┴───┘
  860.    - Blue is normally the underline color for monochrome systems.
  861.    - Procomm Plus has an option that will show actual underlined characters on
  862.      EGA/VGA systems. To turn underline off, a reset color needs to be sent.
  863.  
  864. Example:
  865.      aunderline(acurattr=(acurattr&248)|1);  // True for ANSI, NANSI
  866.      // This will set acurattr=(acurattr&240)|1. This changes the foreground 
  867.      // to blue (1) only and all other color bits same.
  868.  
  869.  
  870. ############
  871. # areverse # Set current color to a color defined by reverse command
  872. ############
  873. Declaration:  char *areverse(equation)            macro-> calls acmd
  874.  
  875. Remark: Returns an ANSI string that will change to the reverse color, acurattr
  876. must be updated manually. Equation is designed for this purpose. Use equation 
  877. in the form: acurattr=xxx where xxx is the value you expect acurattr will
  878. result. If you leave equation blank, make sure to update acurattr on a
  879. separate line. You MUST update acurattr or you could get unexpected colors.
  880.    ┌──────────────┬──────┬──────────┬───┬──────────┬───┐
  881.    │Color Function│Interp│Foreground│HiL│Background│Blk│
  882.    ├──────────────┼──────┼──────────┼───┼──────────┼───┤
  883.    │              │ANSI  │ black  0 │   │ ltgray 7 │   │
  884.    │ Reverse      │NANSI │(backgrnd)│   │(foregrnd)│   │ **
  885.    │              │FANSI │(backgrnd)│   │(foregrnd)│   │ **
  886.    │   ESC[7m     │QMODEM│ black  0 │off│ ltgray 7 │off│
  887.    │              │PCPLUS│ black  0 │   │ ltgray 7 │   │
  888.    │              │TELIX │ black  0 │off│ ltgray 7 │   │
  889.    └──────────────┴──────┴──────────┴───┴──────────┴───┘
  890.    - NANSI and FANSI swap the foreground and background colors only.
  891.  
  892. Example:
  893.      areverse(acurattr=ATTR(BLACK, LIGHTGRAY));  // True for QMODEM
  894.      // This will set acurattr=112. This changes the color to black on
  895.      // lightgray, highlight and blink are off.
  896.  
  897.  
  898. ##############
  899. # ainvisible # Set current color to a color defined by invisible command
  900. ##############
  901. Declaration:  char *ainvisible(equation)          macro-> calls acmd
  902.  
  903. Remark: Returns an ANSI string that will change to the invisible color,
  904. acurattr must be updated manually. Equation is designed for this purpose. Use
  905. equation in the form: acurattr=xxx where xxx is the value you expect acurattr
  906. will result. If you leave equation blank, make sure to update acurattr on a
  907. separate line. You MUST update acurattr or you could get unexpected colors.
  908.    ┌──────────────┬──────┬──────────┬───┬──────────┬───┐
  909.    │Color Function│Interp│Foreground│HiL│Background│Blk│
  910.    ├──────────────┼──────┼──────────┼───┼──────────┼───┤
  911.    │              │ANSI  │ black  0 │on │ black  0 │   │
  912.    │ Invisible    │NANSI │(backgrnd)│   │          │   │ **
  913.    │              │FANSI │(backgrnd)│off│          │   │ **
  914.    │   ESC[8m     │QMODEM│ ltgray 7 │on │ black  0 │off│
  915.    │              │PCPLUS│(dflt bkg)│   │(dflt bkg)│   │ **
  916.    │              │TELIX │(backgrnd)│   │          │   │
  917.    └──────────────┴──────┴──────────┴───┴──────────┴───┘
  918.    - NANSI and FANSI set the foreground color always equal to the background
  919.      color until a reset or a cancel invisible (28) is sent. Ie, if you change
  920.      the background color, the foreground will change to the same color.
  921.    - Procomm Plus sets both the foreground and background colors to the
  922.      default terminal background color as found in the options menu.
  923.  
  924. Example:
  925.      ainvisible(acurattr=DARKGRAY|(acurattr&BLINK));   // True for ANSI
  926.      // This will set acurattr=8+(current blink bit). This changes the color 
  927.      // to darkgray on black, blink is unchanged.
  928.  
  929.  
  930. ################
  931. # anoinvisible # Turn invisible off, for NANSI and FANSI
  932. ################
  933. Declaration:  char *anoinvisible(equation)        macro-> calls acmd
  934.  
  935. Remark: Returns an ANSI string that will turn off the invisible color,
  936. acurattr must be updated manually. Equation is designed for this purpose. Use
  937. equation in the form: acurattr=xxx where xxx is the value you expect acurattr
  938. will result. If you leave equation blank, make sure to update acurattr on a
  939. separate line. You MUST update acurattr or you could get unexpected colors.
  940. This function is for NANSI and FANSI only because they cancel the foreground
  941. color altogether. See Invisible chart notes above.
  942.  
  943.  
  944.  
  945. *LOCATION FUNCTIONS*
  946.  
  947.      The location functions define 2 char variables. They are axpos and aypos.
  948. These variables must be updated to reflect the current cursor locations on the
  949. screen before any of the location functions are executed. This is not
  950. automatically done since none of the output functions are internal. If you are
  951. writing your own output functions, include calculations that tell define the
  952. current cursor coordinates.
  953.  
  954.      Note also that none of the location functions below do any bounds
  955. checking. Ie, do not pass values for axpos or aypos that are beyond the
  956. dimensions of the screen. Most ANSI emulators tend to have built in boundary
  957. checking so the cursor will not go beyond screen coordinates, but OptANSI does
  958. not check current values of axpos or aypos. If there is every any doubt at any
  959. point in your program where bounds might have been exceeded, use aupdatexy()
  960. functions to reevaluate axpos and aypos.
  961.  
  962.  
  963. ###########
  964. # agotoxy # Locate the cursor to new x and y location
  965. ###########
  966. Declaration:  char *agotoxy(char x, char y)       function
  967.  
  968. Remark: Returns an optimized ANSI string that will place the cursor at the
  969. desired location on the screen, updates axpos and aypos. Equivalent to conio's
  970. gotoxy() function.
  971.  
  972.  
  973. ################
  974. # aforcegotoxy # Forces locate of the cursor to x and y ignoring optimizations
  975. ################
  976. Declaration:  char *aforcegotoxy(char x, char y)  macro-> calls agotoxy
  977.  
  978. Remark: Returns a full ANSI string that will place the cursor at the desired
  979. location on the screen, updating axpos and ypos. This function is like agotoxy
  980. except that it will send the complete ANSI string as if the cursor location
  981. was reinitialized, ie it ignores the previous axpos and aypos values when
  982. returning the new location. For instance, lets say that you are worried about
  983. line noise through the modem and axpos or aypos possibly become obscured,
  984. aforcegotoxy(1, 1) would ensure that x and y equal 1 by ignoring internal
  985. optimizations.
  986.  
  987.  
  988. #########
  989. # adown # Move the cursor down y positions
  990. #########
  991. Declaration:  char *adown(char y)                 function
  992.  
  993. Remark: Returns an optimized ANSI string that will move the cursor down y
  994. positions.
  995.  
  996.  
  997. #######
  998. # aup # Move the cursor up y positions
  999. #######
  1000. Declaration:  char *aup(char y)                   macro-> calls acmd
  1001.  
  1002. Remark: Returns an optimized ANSI string that will move the cursor up y
  1003. positions.
  1004.  
  1005.  
  1006. ##########
  1007. # aright # Move the cursor right x positions
  1008. ##########
  1009. Declaration:  char *aright(char x)                macro-> calls acmd
  1010.  
  1011. Remark: Returns an ANSI string that will move the cursor right x positions.
  1012.  
  1013.  
  1014. #########
  1015. # aleft # Move the cursor left x positions
  1016. #########
  1017. Declaration:  char *aleft(char x)                 macro-> calls acmd
  1018.  
  1019. Remark: Returns an optimized ANSI string that will move the cursor left x
  1020. positions.
  1021.  
  1022.  
  1023. #########
  1024. # ahome # Move cursor to top left corner of screen: 1, 1
  1025. #########
  1026. Declaration:  char *ahome()                       macro-> calls agotoxy
  1027.  
  1028. Remark: Returns an optimized ANSI string that will home the cursor to the top
  1029. left cursor position, axpos=1 and aypos=1.
  1030.  
  1031.  
  1032. ###############
  1033. # asavecursor # Save current cursor position
  1034. ###############
  1035. Declaration:  char *asavecursor()                 function
  1036.  
  1037. Remark: Returns an optimized ANSI string that will save the current cursor
  1038. position. arestorecursor will restore the cursor back to this saved position.
  1039. NOTE: asavecursor does not nest. It can only store one cursor position.
  1040.  
  1041.  
  1042. ##################
  1043. # arestorecursor # Restore cursor position to saved
  1044. ##################
  1045. Declaration:  char *arestorecursor()              function
  1046.  
  1047. Remark: Returns an optimized ANSI string that will return the cursor to the
  1048. last position saved by asavecursor. If no position was last saved by
  1049. asavecursor, then the cursor will not relocate. Some ANSI implementations
  1050. assume position 1,1 for prestored location.
  1051.  
  1052. Example:
  1053.      agotoxy(5, 5);      // Locate to position 5, 5
  1054.      asavecursor()       // Saves 5, 5
  1055.      agotoxy(1, 1);      // Locates to 1, 1
  1056.      arestorecursor();   // Returns cursor to 5, 5
  1057.  
  1058.  
  1059. ############
  1060. # awherexy # Interpret x and y cursor locations from atest result string
  1061. ############
  1062. Declaration:  unsigned awherexy(char *s)          function
  1063.  
  1064. Remark: This function is very similar to aresult() and can be used in the same
  1065. way, probably doing a better job. The atest response string has the cursor x
  1066. and y locations. awherexy() will extract this information into an x and y
  1067. cursor location. aresult() doesn't extract this information. awherexy()
  1068. returns an unsigned integer whose most significant byte is the x location and
  1069. the least significant byte is the y location. The awherexy() function should
  1070. follow atest().
  1071.  
  1072. Example:
  1073.      char s[15];
  1074.      unsigned i;
  1075.      atest();       // asks ANSI for cursor location
  1076.      readbuf(&s);   // reads input buffer until enter
  1077.      i=awherexy(s);
  1078.      axpos=i >> 8;  // MSB
  1079.      aypos=i & 256; // LSB
  1080.  
  1081. NOTE: Another use for awherexy that is not otherwise obvious is the ability to
  1082. extract screen dimensions. It works because ANSI emulators have boundary
  1083. constraining, such that if you put agotoxy(99, 99); before the above example
  1084. fragment above, it will locate the cursor to position 99, 99 or the screen
  1085. boundaries whichever comes first. You can then use awherexy() to extract the
  1086. current position and therefore the bounds. For instance, if the screen
  1087. dimensions are 80x25, 80,25 will be returned.
  1088.  
  1089.  
  1090.  
  1091. *OTHER FUNCTIONS*
  1092.  
  1093.      The miscellaneous functions below are only available locally on a DOS
  1094. machine. Most telecommunications programs do not support them. These commands
  1095. are discouraged from use because they can effect the way the keyboard behaves
  1096. and change modes that make many ANSI functions inactive or misbehave. However,
  1097. because ANSI implements them, they are supported by OptANSI as well. They can
  1098. be very useful functions to very specific applications.
  1099.  
  1100.  
  1101. #############
  1102. # akeyboard # Reassign keyboard keys
  1103. #############
  1104. Declaration:  char *akeyboard(int key, char *str, char *buf)
  1105.                                                   function
  1106.  
  1107. Remark: Returns an ANSI string that will redefine keys on your keyboard, like
  1108. a macro. For instance, if you send the key ALT1 to be reassigned to the macro
  1109. "I use OptANSI!", every time you hit ALT1 from DOS, that macro will display.
  1110. A separate buffer is needed by this function because the global buffer space
  1111. may be too small for str. Define this buffer space in your program and point
  1112. buf to it.  The parameter key is the input key you wish to define. To use
  1113. special keys like the function keys, arrows, or ALT-combinations, use the SKEY
  1114. macro defined below. For redefining one letter keys or control sequences like
  1115. CTRL-A, use that character value (CTRL-A is 1). If you want to make
  1116. complicated command sequences similar a batch language, you must include all
  1117. newline chars as well. For instance, to do a dir followed by a pause, use:
  1118.  
  1119.   char buf[256];
  1120.   akeyboard(SKEY(ALT1), "DIR /w\nPAUSE\n", &buf);
  1121.  
  1122. SKEY (below) expands ALT1 which is defined in SKEYS.H for use with
  1123. akeyboard(). The parameter buf is used to point to new buffer. It needs to be
  1124. large enough to accept all characters you define in str + 11.
  1125.  
  1126.  
  1127. ########
  1128. # SKEY # Calculates value for special keys for use in parameter for akeyboard
  1129. ########
  1130. Declaration:  int SKEY(char key)                  macro-> 0,key
  1131.  
  1132. Remark: This macro is necessary to expand special keys like Function keys,
  1133. arrows, all ALT combinations, and other combinations of the above into a
  1134. parameter which can be used by akeyboard (defined above). Make sure to include
  1135. the header file SKEYS.H which defines most of the definable special keys.
  1136. These macros are listed below:
  1137.      UP, DOWN, LEFT, RIGHT, PGUP, PGDOWN, HOME, END
  1138.      CTRLLEFT, CTRLRIGHT, CTRLPGUP, CTRLPGDOWN, CTRLHOME, CTRLEND
  1139.      F1 - F10, CTRLF1 - CTRLF10, SHFTF1 - SHFTF10, ALTF1 - ALTF10
  1140.      ALTA - ALTZ, ALT0 - ALT9
  1141.  
  1142.  
  1143. #########
  1144. # amode # Function for use with asetmode and aresetmode
  1145. #########
  1146. Declaration:  char *amode(int mode, char cmd)     function
  1147.  
  1148. Remark: See asetmode and aresetmode for more details.
  1149.  
  1150.  
  1151. ############
  1152. # asetmode # Sets mode to an ANSI defined mode or changes display rules
  1153. ############
  1154. Declaration:  char *asetmode(int mode)            macro-> calls amode
  1155.  
  1156. Remark: This function returns an ANSI string that changes the current video
  1157. mode or sets an ANSI variable to on/true. Set mode to a value listed below.
  1158. NOTE also that changing to another mode may relocate the cursor and/or change
  1159. the color. The global variables axpos, aypos, and acurattr must be updated
  1160. manually.
  1161.  
  1162. Macros, Mode Values, and their result of usage:
  1163.      BW40          0   Text 40x25, 16 colors  (ANSI colors override B&W modes)
  1164.      C40           1   Text 40x25, 16 colors
  1165.      BW80          2   Text 80x25, 16 colors  (ANSI colors override B&W modes)
  1166.      C80           3   Text 80x25, 16 colors
  1167.      G320_200      4   Graphics 320x200, 4 colors
  1168.      G320_200GR    5   Graphics 320x200, 4 grey colors
  1169.      G640_200BW    6   Graphics 640x200, 2 colors - black & white
  1170.      aCURSORWRAP   7   -- Cursor wrap on/off
  1171.      G320_200V    13   Graphics 320x200, 16 colors, (VGA)
  1172.      G640_200V    14   Graphics 640x200, 16 colors, (VGA)
  1173.      G640_350V    16   Graphics 640x350, 16 colors, (VGA)
  1174.      G640_480BWV  17   Graphics 640x480, 2 colors - black & white, (VGA)
  1175.      G640_480V    18   Graphics 640x480, 16 colors, (VGA)
  1176.      G300_200V    19   Graphics 300x200, 256 colors, (VGA)
  1177.      ROWS43       43   43 line mode in modes 0-3 (EGA, NANSI extension)
  1178.      ROWS50       50   50 line mode in modes 0-3 (VGA, NANSI extension)
  1179.      aBIOSTTY     97   -- ANSI BIOS/WRITE_TTY (NANSI extension)
  1180.      aFASTSCROLL  98   -- FAST SCROLL on/off (NANSI extension)
  1181.      aGRAPHICSCURSOR 99-- Graphics cursor on/off (NANSI extension)
  1182.                   n    Other mode not listed above (NANSI extension)
  1183.  
  1184. VGA modes are supported by ANSI versions DOS 4.0 and above. Mode values do not
  1185. necessarily match BIOS values.
  1186.  
  1187. NOTE: On/Off switches like Cursor wrap on/off are set on with asetmode and
  1188. turned off with aresetmode (below). So to turn cursor wrap on you'd use
  1189. asetmode(aCURSORWRAP). To turn it off you'd use aresetmode(aCURSORWRAP).
  1190. You may use the macros defined in OPTANSI.H: aCURSORWRAP, aBIOS, aWRITE_TTY,
  1191. aBIOSTTY, aFASTSCROLL, and aGRAPHICSCURSOR.
  1192.  
  1193.  
  1194. ##############
  1195. # aresetmode # Resets mode to an ANSI defined mode or changes display rules
  1196. ##############
  1197. Declaration:  char *aresetmode(int mode)          macro-> calls amode
  1198.  
  1199. Remark: This function returns an ANSI string that changes the current video
  1200. mode or sets an ANSI variable to off/false. Set mode to a value listed in
  1201. asetmode above. NOTE also that changing to another mode may relocate the
  1202. cursor and/or change the color. The global variables axpos, aypos, and
  1203. acurattr must be updated manually.
  1204.  
  1205. NOTE: As far as changing video modes, there may or may not be a difference
  1206. between asetmode and aresetmode. This is dependant on the ANSI driver. I have
  1207. not noticed any differences with the tests that I've run.
  1208.  
  1209.  
  1210. #############
  1211. # atextmode # Switch to a text mode, though really the same as asetmode
  1212. #############
  1213. Declaration:  char *atextmode(int mode)           macro-> calls asetmode
  1214.  
  1215. Remark: This is a macro equivalent to conio's textmode. You can use conio's
  1216. BW40, C40, BW80, and C80 macros, but any others have different effects. This
  1217. function is the same thing as asetmode.
  1218.  
  1219.  
  1220. ###############
  1221. # acursorwrap # Turn on cursorwrap
  1222. ###############
  1223. Declaration:  char *acursorwrap()                 macro-> calls asetmode
  1224.  
  1225. Remark: This function will return an ANSI string that will turn on cursor
  1226. wrap.
  1227.  
  1228.  
  1229. #################
  1230. # anocursorwrap # Turn off cursorwrap
  1231. #################
  1232. Declaration:  char *anocursorwrap()               macro-> calls aresetmode
  1233.  
  1234. Remark: This function will return an ANSI string that will turn off cursor
  1235. wrap.
  1236.  
  1237.  
  1238.  
  1239. *COMPILATION NOTES*
  1240.  
  1241.      If you are a registered user of the OptANSI library, you will be able to
  1242. compile your own versions of the code.
  1243.  
  1244.      Take special caution when modifying AGOTOXY.C and ACOLOR.C because much
  1245. of the code is combined meta or inline assembly. These and some of the other
  1246. functions use registers in place of variables for faster and tighter
  1247. execution. This practice is safe with BC++ as long as you use instructions
  1248. that do not rely on the selected registers. To ensure safe compilation on
  1249. these files, you can use your debugger or compile your code to assembly to
  1250. examine it.
  1251.  
  1252.      When compiling there are some special definitions you can set in
  1253. OPTANSI.H to include certain compilations. They are located at the top of
  1254. OPTANSI.H and are only defined for OptANSI functions. They are listed below:
  1255.  
  1256. NANSI
  1257.      If #define NANSI is 1 in OPTANSI.H during compilation, special NANSI
  1258. optimizations which are not otherwise included will be included. This will add
  1259. another 120 bytes of code. This macro definition is different than the aNANSI
  1260. flag because NANSI specifies whether you want NANSI (and FANSI) support code
  1261. included at all, whereas the aNANSI flag determines during execution whether
  1262. the option is available. aNANSI has no effect without NANSI being true. Note:
  1263. acolor will try to use special NANSI output to turn off highlight and blink if
  1264. ashortcuts has the aNANSI flag on and NANSI support is compiled in, so make
  1265. sure that you check for NANSI presence before setting the aNANSI flag. You can
  1266. do this by either asking the user or sending a NANSI only command and then
  1267. testing the status literally.
  1268.  
  1269. SIZE
  1270.      If #define SIZE is 1 in OPTANSI.H during compilation, the C preprocessor
  1271. will compile aspects of the code that are more likely to produce smaller code
  1272. by calling functions instead of multi-purpose macros. This is done at the cost
  1273. of speed so define SIZE to 0 for faster code. NOTE: This option was removed
  1274. until further tests could be performed. It is defined for future use.
  1275.  
  1276. REGISTERED
  1277.      If #define REGISTER is 1 in OPTANSI.H during compilation, all excess demo
  1278. code will be eliminated for registered version and tightened code.
  1279.  
  1280.  
  1281.      There are also other macros defined in OPTANSI.H that may be useful to
  1282. your implementation. For instance if you are using C++, you can use EXTERN in
  1283. place of extern. This will use extern "C" so that you can use standard C
  1284. functions as with OptANSI.
  1285.  
  1286. ------------------------------------------------------------------------------
  1287. AOPT is a trademark or copyright of Michael Dannov
  1288. ANSI.SYS is a trademark or copyright of Microsoft Corp.
  1289. NANSI.SYS is a trademark or copyright of Daniel Kegal.
  1290. FCONSOLE.DEV and FANSI-CONSOLE are trademarks or copyright of Hersey Micro
  1291.   Consulting, Inc.
  1292. Procomm Plus is a trademark or copyright of DataStorm Technologies, Inc.
  1293. QMODEM is a trademark or copyright of Mustang Software, Inc.
  1294. TELIX is a trademark or copyright of Exis Inc and Colin Sampaleanu
  1295.